home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 April: Mac OS SDK / Dev.CD Apr 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Interfaces / PInterfaces / NameRegistry.p < prev    next >
Encoding:
Text File  |  1996-09-22  |  11.8 KB  |  364 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        NameRegistry.p
  3.  
  4.      Contains:    NameRegistry Interfaces
  5.  
  6.      Version:    Technology:    PowerSurge 1.0.2.
  7.                  Package:    Universal Interfaces 2.1.4
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.
  10.                  All rights reserved.
  11.  
  12.      Bugs?:        If you find a problem with this file, use the Apple Bug Reporter
  13.                  stack.  Include the file and version information (from above)
  14.                  in the problem description and send to:
  15.                      Internet:    apple.bugs@applelink.apple.com
  16.                      AppleLink:    APPLE.BUGS
  17.  
  18. }
  19.  
  20. {$IFC UNDEFINED UsingIncludes}
  21. {$SETC UsingIncludes := 0}
  22. {$ENDC}
  23.  
  24. {$IFC NOT UsingIncludes}
  25.  UNIT NameRegistry;
  26.  INTERFACE
  27. {$ENDC}
  28.  
  29. {$IFC UNDEFINED __NAMEREGISTRY__}
  30. {$SETC __NAMEREGISTRY__ := 1}
  31.  
  32. {$I+}
  33. {$SETC NameRegistryIncludes := UsingIncludes}
  34. {$SETC UsingIncludes := 1}
  35.  
  36. {$IFC UNDEFINED __TYPES__}
  37. {$I Types.p}
  38. {$ENDC}
  39.  
  40. {$PUSH}
  41. {$ALIGN POWER}
  42. {$LibExport+}
  43.  
  44. {
  45.  * Name Registry - API for device driver name registration
  46.  *
  47.  * This interface provides access to the namespace used
  48.  * by device drivers.  The data structures and entry points
  49.  * are specialized and simplified for device driver use.
  50. }
  51. {
  52.  //////////////////////////////////////////////////////////////////////////////
  53. //
  54. // Data Structures
  55. //
  56. }
  57. {
  58.  //////////////////////////////////////////////////////////////////////////////
  59. // 
  60. // Foundation Types
  61. //
  62. }
  63. {  Value of a property  }
  64.  
  65. TYPE
  66.     RegPropertyValue                    = Ptr;
  67. {  Length of property value  }
  68.     RegPropertyValueSize                = UInt32;
  69. {
  70.  //////////////////////////////////////////////////////////////////////////////
  71. // 
  72. // RegEntryID    :    The Global x-Namespace Entry Identifier
  73. //
  74. }
  75. {  RegEntryID:    The Global Entry ID }
  76.     RegEntryID = RECORD
  77.         contents:                ARRAY [0..15] OF SInt8;
  78.     END;
  79.     RegEntryIDPtr                         = ^RegEntryID;
  80. {
  81.  //////////////////////////////////////////////////////////////////////////////
  82. //
  83. // Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  84. //
  85. //    * Names are a colon-separated list of name components.  Name components
  86. //      may not themselves contain colons.  
  87. //    * Names are presented as null-terminated ASCII character strings.
  88. //    * Names follow similar parsing rules to Apple file system absolute
  89. //      and relative paths.  However the '::' parent directory syntax is
  90. //      not currently supported.
  91. }
  92. {  Max length of Entry Name  }
  93.  
  94. CONST
  95.     kRegCStrMaxEntryNameLength    = 47;
  96.  
  97. {  Entry Names are single byte ASCII  }
  98.  
  99. TYPE
  100.     RegCStrEntryName                    = CHAR;
  101.     RegCStrEntryNamePtr                    = ^CHAR;
  102. {  length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1 }
  103.     RegCStrEntryNameBuf                    = PACKED ARRAY [0..47] OF CHAR;
  104.     RegCStrPathName                        = CHAR;
  105.     RegPathNameSize                        = UInt32;
  106.  
  107. CONST
  108.     kRegPathNameSeparator        = $3A;                            {  ':'   }
  109.     kRegEntryNameTerminator        = $00;                            {  '\0'  }
  110.     kRegPathNameTerminator        = $00;                            {  '\0'  }
  111.  
  112. {
  113.  //////////////////////////////////////////////////////////////////////////////
  114. //
  115. // Property Name and ID Definitions
  116. //    (Applies to all Properties Regardless of NameSpace)
  117. }
  118.     kRegMaximumPropertyNameLength = 31;                            {  Max length of Property Name  }
  119.     kRegPropertyNameTerminator    = $00;                            {  '\0'  }
  120.  
  121.  
  122. TYPE
  123.     RegPropertyName                        = CHAR;
  124.     RegPropertyNamePtr                    = ^CHAR;
  125. {
  126.  //////////////////////////////////////////////////////////////////////////////
  127. //
  128. // Iteration Operations
  129. //
  130. //    These specify direction when traversing the name relationships
  131. }
  132.     RegIterationOp                        = UInt32;
  133.     RegEntryIterationOp                    = RegIterationOp;
  134.  
  135. CONST
  136.                                                                 {  Absolute locations }
  137.     kRegIterRoot                = $00000002;                    {  "Upward" Relationships     }
  138.     kRegIterParents                = $00000003;                    {  include all  parent(s) of entry  }
  139.                                                                 {  "Downward" Relationships }
  140.     kRegIterChildren            = $00000004;                    {  include all children  }
  141.     kRegIterSubTrees            = $00000005;                    {  include all sub trees of entry  }
  142.     kRegIterDescendants            = $00000005;                    {  include all descendants of entry  }
  143.                                                                 {  "Horizontal" Relationships     }
  144.     kRegIterSibling                = $00000006;                    {  include all siblings  }
  145.                                                                 {  Keep doing the same thing }
  146.     kRegIterContinue            = $00000001;
  147.  
  148. {
  149.  //////////////////////////////////////////////////////////////////////////////
  150. //
  151. // Name Entry and Property Modifiers
  152. //
  153.  
  154. //
  155. // Modifiers describe special characteristics of names
  156. // and properties.  Modifiers might be supported for
  157. // some names and not others.
  158. // 
  159. // Device Drivers should not rely on functionality
  160. // specified as a modifier.
  161. }
  162.  
  163. TYPE
  164.     RegModifiers                        = UInt32;
  165.     RegEntryModifiers                    = RegModifiers;
  166.     RegPropertyModifiers                = RegModifiers;
  167.  
  168. CONST
  169.     kRegNoModifiers                = $00000000;                    {  no entry modifiers in place  }
  170.     kRegUniversalModifierMask    = $0000FFFF;                    {  mods to all entries  }
  171.     kRegNameSpaceModifierMask    = $00FF0000;                    {  mods to all entries within namespace  }
  172.     kRegModifierMask            = $FF000000;                    {  mods to just this entry  }
  173.  
  174. {  Universal Property Modifiers  }
  175.     kRegPropertyValueIsSavedToNVRAM = $00000020;                {  property is non-volatile (saved in NVRAM)  }
  176.     kRegPropertyValueIsSavedToDisk = $00000040;                    {  property is non-volatile (saved on disk)  }
  177.  
  178. {
  179.  ///////////////////////
  180. //
  181. // The Registry API
  182. //
  183. /////////////////////// 
  184. }
  185. {
  186.  ///////////////////////
  187. //
  188. // Entry Management
  189. //
  190. /////////////////////// 
  191. }
  192. {
  193. -------------------------------
  194.  * EntryID handling
  195. }
  196. {
  197.  * Initialize an EntryID to a known invalid state
  198.  *   note: invalid != uninitialized
  199. }
  200. FUNCTION RegistryEntryIDInit(VAR id: RegEntryID): OSStatus; C;
  201. {
  202.  * Compare EntryID's for equality or if invalid
  203.  *
  204.  * If a NULL value is given for either id1 or id2, the other id 
  205.  * is compared with an invalid ID.  If both are NULL, the id's 
  206.  * are consided equal (result = true). 
  207. }
  208. FUNCTION RegistryEntryIDCompare({CONST}VAR id1: RegEntryID; {CONST}VAR id2: RegEntryID): BOOLEAN; C;
  209. {
  210.  * Copy an EntryID
  211. }
  212. FUNCTION RegistryEntryIDCopy({CONST}VAR src: RegEntryID; VAR dst: RegEntryID): OSStatus; C;
  213. {
  214.  * Free an ID so it can be reused.
  215. }
  216. FUNCTION RegistryEntryIDDispose(VAR id: RegEntryID): OSStatus; C;
  217. {
  218. -------------------------------
  219.  * Adding and removing entries
  220.  *
  221.  * If (parentEntry) is NULL, the name is assumed
  222.  * to be a rooted path. It is rooted to an anonymous, unnamed root.
  223. }
  224. FUNCTION RegistryCStrEntryCreate({CONST}VAR parentEntry: RegEntryID; {CONST}VAR name: RegCStrPathName; VAR newEntry: RegEntryID): OSStatus; C;
  225. FUNCTION RegistryEntryDelete({CONST}VAR id: RegEntryID): OSStatus; C;
  226.  
  227. TYPE
  228.     RegEntryIter = ^LONGINT;
  229. {
  230.  * create/dispose the iterator structure
  231.  *   defaults to root with relationship = kRegIterDescendants
  232. }
  233. FUNCTION RegistryEntryIterateCreate(VAR cookie: RegEntryIter): OSStatus; C;
  234. FUNCTION RegistryEntryIterateDispose(VAR cookie: RegEntryIter): OSStatus; C;
  235. {
  236.  * set Entry Iterator to specified entry
  237. }
  238. FUNCTION RegistryEntryIterateSet(VAR cookie: RegEntryIter; {CONST}VAR startEntryID: RegEntryID): OSStatus; C;
  239. {
  240.  * Return each value of the iteration
  241.  *
  242.  * return entries related to the current entry
  243.  * with the specified relationship
  244. }
  245. FUNCTION RegistryEntryIterate(VAR cookie: RegEntryIter; relationship: RegEntryIterationOp; VAR foundEntry: RegEntryID; VAR done: BOOLEAN): OSStatus; C;
  246. {
  247.  * return entries with the specified property
  248.  *
  249.  * A NULL RegPropertyValue pointer will return an
  250.  * entry with the property containing any value.
  251. }
  252. FUNCTION RegistryEntrySearch(VAR cookie: RegEntryIter; relationship: RegEntryIterationOp; VAR foundEntry: RegEntryID; VAR done: BOOLEAN; {CONST}VAR propertyName: RegPropertyName; propertyValue: UNIV Ptr; propertySize: RegPropertyValueSize): OSStatus; C;
  253. {
  254. --------------------------------
  255.  * Find a name in the namespace
  256.  *
  257.  * This is the fast lookup mechanism.
  258.  * NOTE:  A reverse lookup mechanism
  259.  *      has not been provided because
  260.  *        some name services may not
  261.  *        provide a fast, general reverse
  262.  *        lookup.
  263. }
  264. FUNCTION RegistryCStrEntryLookup({CONST}VAR searchPointID: RegEntryID; {CONST}VAR pathName: RegCStrPathName; VAR foundEntry: RegEntryID): OSStatus; C;
  265. {
  266. ---------------------------------------------
  267.  * Convert an entry to a rooted name string
  268.  *
  269.  * A utility routine to turn an Entry ID
  270.  * back into a name string.
  271. }
  272. FUNCTION RegistryEntryToPathSize({CONST}VAR entryID: RegEntryID; VAR pathSize: RegPathNameSize): OSStatus; C;
  273. FUNCTION RegistryCStrEntryToPath({CONST}VAR entryID: RegEntryID; VAR pathName: RegCStrPathName; pathSize: RegPathNameSize): OSStatus; C;
  274. {
  275.  * Parse a path name.
  276.  *
  277.  * Retrieve the last component of the path, and
  278.  * return a spec for the parent.
  279. }
  280. FUNCTION RegistryCStrEntryToName({CONST}VAR entryID: RegEntryID; VAR parentEntry: RegEntryID; VAR nameComponent: RegCStrEntryName; VAR done: BOOLEAN): OSStatus; C;
  281. {
  282.  //////////////////////////////////////////////////////
  283. //
  284. // Property Management
  285. //
  286. ////////////////////////////////////////////////////// 
  287. }
  288. {
  289. -------------------------------
  290.  * Adding and removing properties
  291. }
  292. FUNCTION RegistryPropertyCreate({CONST}VAR entryID: RegEntryID; {CONST}VAR propertyName: RegPropertyName; propertyValue: UNIV Ptr; propertySize: RegPropertyValueSize): OSStatus; C;
  293. FUNCTION RegistryPropertyDelete({CONST}VAR entryID: RegEntryID; {CONST}VAR propertyName: RegPropertyName): OSStatus; C;
  294. {
  295. ---------------------------
  296.  * Traversing the Properties of a name
  297.  *
  298. }
  299.  
  300. TYPE
  301.     RegPropertyIter = ^LONGINT;
  302. FUNCTION RegistryPropertyIterateCreate({CONST}VAR entry: RegEntryID; VAR cookie: RegPropertyIter): OSStatus; C;
  303. FUNCTION RegistryPropertyIterateDispose(VAR cookie: RegPropertyIter): OSStatus; C;
  304. FUNCTION RegistryPropertyIterate(VAR cookie: RegPropertyIter; VAR foundProperty: RegPropertyName; VAR done: BOOLEAN): OSStatus; C;
  305. {
  306.  * Get the value of the specified property for the specified entry.
  307.  *
  308. }
  309. FUNCTION RegistryPropertyGetSize({CONST}VAR entryID: RegEntryID; {CONST}VAR propertyName: RegPropertyName; VAR propertySize: RegPropertyValueSize): OSStatus; C;
  310. {
  311.  * (*propertySize) is the maximum size of the value returned in the buffer
  312.  * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  313.  * value returned.
  314. }
  315. FUNCTION RegistryPropertyGet({CONST}VAR entryID: RegEntryID; {CONST}VAR propertyName: RegPropertyName; propertyValue: UNIV Ptr; VAR propertySize: RegPropertyValueSize): OSStatus; C;
  316. FUNCTION RegistryPropertySet({CONST}VAR entryID: RegEntryID; {CONST}VAR propertyName: RegPropertyName; propertyValue: UNIV Ptr; propertySize: RegPropertyValueSize): OSStatus; C;
  317. {
  318.  //////////////////////////////////////////////////////
  319. //
  320. // Modibute (err, I mean Modifier) Management
  321. //
  322. ////////////////////////////////////////////////////// 
  323. }
  324. {
  325.  * Modifiers describe special characteristics of names
  326.  * and properties.  Modifiers might be supported for
  327.  * some names and not others.
  328.  * 
  329.  * Device Drivers should not rely on functionality
  330.  * specified as a modifier.  These interfaces
  331.  * are for use in writing Experts.
  332. }
  333. {
  334.  * Get and Set operators for entry modifiers
  335. }
  336. FUNCTION RegistryEntryGetMod({CONST}VAR entry: RegEntryID; VAR modifiers: RegEntryModifiers): OSStatus; C;
  337. FUNCTION RegistryEntrySetMod({CONST}VAR entry: RegEntryID; modifiers: RegEntryModifiers): OSStatus; C;
  338. {
  339.  * Get and Set operators for property modifiers
  340. }
  341. FUNCTION RegistryPropertyGetMod({CONST}VAR entry: RegEntryID; {CONST}VAR name: RegPropertyName; VAR modifiers: RegPropertyModifiers): OSStatus; C;
  342. FUNCTION RegistryPropertySetMod({CONST}VAR entry: RegEntryID; {CONST}VAR name: RegPropertyName; modifiers: RegPropertyModifiers): OSStatus; C;
  343. {
  344.  * Iterator operator for entry modifier search
  345. }
  346. FUNCTION RegistryEntryMod(VAR cookie: RegEntryIter; relationship: RegEntryIterationOp; VAR foundEntry: RegEntryID; VAR done: BOOLEAN; matchingModifiers: RegEntryModifiers): OSStatus; C;
  347. {
  348.  * Iterator operator for entries with matching 
  349.  * property modifiers
  350. }
  351. FUNCTION RegistryEntryPropertyMod(VAR cookie: RegEntryIter; relationship: RegEntryIterationOp; VAR foundEntry: RegEntryID; VAR done: BOOLEAN; matchingModifiers: RegPropertyModifiers): OSStatus; C;
  352.  
  353.  
  354. {$ALIGN RESET}
  355. {$POP}
  356.  
  357. {$SETC UsingIncludes := NameRegistryIncludes}
  358.  
  359. {$ENDC} {__NAMEREGISTRY__}
  360.  
  361. {$IFC NOT UsingIncludes}
  362.  END.
  363. {$ENDC}
  364.